<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.14.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Vulkan Memory Allocator: VK_EXT_memory_priority</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Vulkan Memory Allocator
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.14.0 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search/",'.html');
</script>
<script type="text/javascript">
$(function() { codefold.init(); });
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search',false);
  $(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a href="index.html">Vulkan Memory Allocator</a></li>  </ul>
</div>
</div><!-- top -->
<div id="doc-content">
<div><div class="header">
  <div class="headertitle"><div class="title">VK_EXT_memory_priority </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>VK_EXT_memory_priority is a device extension that allows to pass additional "priority" value to Vulkan memory allocations that the implementation may use prefer certain buffers and images that are critical for performance to stay in device-local memory in cases when the memory is over-subscribed, while some others may be moved to the system memory.</p>
<p>VMA offers convenient usage of this extension. If you enable it, you can pass "priority" parameter when creating allocations or custom pools and the library automatically passes the value to Vulkan using this extension.</p>
<p>If you want to use this extension in connection with VMA, follow these steps:</p>
<h1 class="doxsection"><a class="anchor" id="vk_ext_memory_priority_initialization"></a>
Initialization</h1>
<p>1) Call <span class="tt">vkEnumerateDeviceExtensionProperties</span> for the physical device. Check if the extension is supported - if returned array of <span class="tt">VkExtensionProperties</span> contains "VK_EXT_memory_priority".</p>
<p>2) Call <span class="tt">vkGetPhysicalDeviceFeatures2</span> for the physical device instead of old <span class="tt">vkGetPhysicalDeviceFeatures</span>. Attach additional structure <span class="tt">VkPhysicalDeviceMemoryPriorityFeaturesEXT</span> to <span class="tt">VkPhysicalDeviceFeatures2::pNext</span> to be returned. Check if the device feature is really supported - check if <span class="tt">VkPhysicalDeviceMemoryPriorityFeaturesEXT::memoryPriority</span> is true.</p>
<p>3) While creating device with <span class="tt">vkCreateDevice</span>, enable this extension - add "VK_EXT_memory_priority" to the list passed as <span class="tt">VkDeviceCreateInfo::ppEnabledExtensionNames</span>.</p>
<p>4) While creating the device, also don't set <span class="tt">VkDeviceCreateInfo::pEnabledFeatures</span>. Fill in <span class="tt">VkPhysicalDeviceFeatures2</span> structure instead and pass it as <span class="tt">VkDeviceCreateInfo::pNext</span>. Enable this device feature - attach additional structure <span class="tt">VkPhysicalDeviceMemoryPriorityFeaturesEXT</span> to <span class="tt">VkPhysicalDeviceFeatures2::pNext</span> chain and set its member <span class="tt">memoryPriority</span> to <span class="tt">VK_TRUE</span>.</p>
<p>5) While creating <a class="el" href="struct_vma_allocator.html" title="Represents main object of this library initialized.">VmaAllocator</a> with <a class="el" href="group__group__init.html#ga200692051ddb34240248234f5f4c17bb" title="Creates VmaAllocator object.">vmaCreateAllocator()</a> inform VMA that you have enabled this extension and feature - add <a class="el" href="group__group__init.html#gga4f87c9100d154a65a4ad495f7763cf7caffdd7a5169be3dbd7cbf6b3619e4f78a">VMA_ALLOCATOR_CREATE_EXT_MEMORY_PRIORITY_BIT</a> to <a class="el" href="struct_vma_allocator_create_info.html#a392ea2ecbaff93f91a7c49f735ad4346" title="Flags for created allocator. Use VmaAllocatorCreateFlagBits enum.">VmaAllocatorCreateInfo::flags</a>.</p>
<h1 class="doxsection"><a class="anchor" id="vk_ext_memory_priority_usage"></a>
Usage</h1>
<p>When using this extension, you should initialize following member:</p>
<ul>
<li><a class="el" href="struct_vma_allocation_create_info.html#a983d39e1a2e63649d78a960aa2fdd0f7" title="A floating-point value between 0 and 1, indicating the priority of the allocation relative to other m...">VmaAllocationCreateInfo::priority</a> when creating a dedicated allocation with <a class="el" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f" title="Set this flag if the allocation should have its own memory block.">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>.</li>
<li><a class="el" href="struct_vma_pool_create_info.html#a16e686c688f6725f119ebf6e24ab5274" title="A floating-point value between 0 and 1, indicating the priority of the allocations in this pool relat...">VmaPoolCreateInfo::priority</a> when creating a custom pool.</li>
</ul>
<p>It should be a floating-point value between <span class="tt">0.0f</span> and <span class="tt">1.0f</span>, where recommended default is <span class="tt">0.5F</span>. Memory allocated with higher value can be treated by the Vulkan implementation as higher priority and so it can have lower chances of being pushed out to system memory, experiencing degraded performance.</p>
<p>It might be a good idea to create performance-critical resources like color-attachment or depth-stencil images as dedicated and set high priority to them. For example:</p>
<div class="fragment"><div class="line">VkImageCreateInfo imgCreateInfo = { VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO };</div>
<div class="line">imgCreateInfo.imageType = VK_IMAGE_TYPE_2D;</div>
<div class="line">imgCreateInfo.extent.width = 3840;</div>
<div class="line">imgCreateInfo.extent.height = 2160;</div>
<div class="line">imgCreateInfo.extent.depth = 1;</div>
<div class="line">imgCreateInfo.mipLevels = 1;</div>
<div class="line">imgCreateInfo.arrayLayers = 1;</div>
<div class="line">imgCreateInfo.format = VK_FORMAT_R8G8B8A8_UNORM;</div>
<div class="line">imgCreateInfo.tiling = VK_IMAGE_TILING_OPTIMAL;</div>
<div class="line">imgCreateInfo.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;</div>
<div class="line">imgCreateInfo.usage = VK_IMAGE_USAGE_SAMPLED_BIT | VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;</div>
<div class="line">imgCreateInfo.samples = VK_SAMPLE_COUNT_1_BIT;</div>
<div class="line"> </div>
<div class="line"><a class="code hl_struct" href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a> allocCreateInfo = {};</div>
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">usage</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a>;</div>
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">flags</a> = <a class="code hl_enumvalue" href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a>;</div>
<div class="line">allocCreateInfo.<a class="code hl_variable" href="struct_vma_allocation_create_info.html#a983d39e1a2e63649d78a960aa2fdd0f7">priority</a> = 1.0f;</div>
<div class="line"> </div>
<div class="line">VkImage img;</div>
<div class="line"><a class="code hl_struct" href="struct_vma_allocation.html">VmaAllocation</a> alloc;</div>
<div class="line"><a class="code hl_function" href="group__group__alloc.html#ga02a94f25679275851a53e82eacbcfc73">vmaCreateImage</a>(allocator, &amp;imgCreateInfo, &amp;allocCreateInfo, &amp;img, &amp;alloc, <span class="keyword">nullptr</span>);</div>
<div class="ttc" id="agroup__group__alloc_html_ga02a94f25679275851a53e82eacbcfc73"><div class="ttname"><a href="group__group__alloc.html#ga02a94f25679275851a53e82eacbcfc73">vmaCreateImage</a></div><div class="ttdeci">VkResult vmaCreateImage(VmaAllocator allocator, const VkImageCreateInfo *pImageCreateInfo, const VmaAllocationCreateInfo *pAllocationCreateInfo, VkImage *pImage, VmaAllocation *pAllocation, VmaAllocationInfo *pAllocationInfo)</div><div class="ttdoc">Function similar to vmaCreateBuffer() but for images.</div></div>
<div class="ttc" id="agroup__group__alloc_html_ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e"><div class="ttname"><a href="group__group__alloc.html#ggaa5846affa1e9da3800e3e78fae2305cca27cde9026a84d34d525777baa41fce6e">VMA_MEMORY_USAGE_AUTO</a></div><div class="ttdeci">@ VMA_MEMORY_USAGE_AUTO</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:553</div></div>
<div class="ttc" id="agroup__group__alloc_html_ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f"><div class="ttname"><a href="group__group__alloc.html#ggad9889c10c798b040d59c92f257cae597a3fc311d855c2ff53f1090ef5c722b38f">VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</a></div><div class="ttdeci">@ VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT</div><div class="ttdoc">Set this flag if the allocation should have its own memory block.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:592</div></div>
<div class="ttc" id="astruct_vma_allocation_create_info_html"><div class="ttname"><a href="struct_vma_allocation_create_info.html">VmaAllocationCreateInfo</a></div><div class="ttdoc">Parameters of new VmaAllocation.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1294</div></div>
<div class="ttc" id="astruct_vma_allocation_create_info_html_a983d39e1a2e63649d78a960aa2fdd0f7"><div class="ttname"><a href="struct_vma_allocation_create_info.html#a983d39e1a2e63649d78a960aa2fdd0f7">VmaAllocationCreateInfo::priority</a></div><div class="ttdeci">float priority</div><div class="ttdoc">A floating-point value between 0 and 1, indicating the priority of the allocation relative to other m...</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1340</div></div>
<div class="ttc" id="astruct_vma_allocation_create_info_html_accb8b06b1f677d858cb9af20705fa910"><div class="ttname"><a href="struct_vma_allocation_create_info.html#accb8b06b1f677d858cb9af20705fa910">VmaAllocationCreateInfo::usage</a></div><div class="ttdeci">VmaMemoryUsage usage</div><div class="ttdoc">Intended usage of memory.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1302</div></div>
<div class="ttc" id="astruct_vma_allocation_create_info_html_add09658ac14fe290ace25470ddd6d41b"><div class="ttname"><a href="struct_vma_allocation_create_info.html#add09658ac14fe290ace25470ddd6d41b">VmaAllocationCreateInfo::flags</a></div><div class="ttdeci">VmaAllocationCreateFlags flags</div><div class="ttdoc">Use VmaAllocationCreateFlagBits enum.</div><div class="ttdef"><b>Definition</b> vk_mem_alloc.h:1296</div></div>
<div class="ttc" id="astruct_vma_allocation_html"><div class="ttname"><a href="struct_vma_allocation.html">VmaAllocation</a></div><div class="ttdoc">Represents single memory allocation.</div></div>
</div><!-- fragment --><p><span class="tt">priority</span> member is ignored in the following situations:</p>
<ul>
<li>Allocations created in custom pools: They inherit the priority, along with all other allocation parameters from the parameters passed in <a class="el" href="struct_vma_pool_create_info.html" title="Describes parameter of created VmaPool.">VmaPoolCreateInfo</a> when the pool was created.</li>
<li>Allocations created in default pools: They inherit the priority from the parameters VMA used when creating default pools, which means <span class="tt">priority == 0.5F</span>. </li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.14.0
</small></address>
</div><!-- doc-content -->
</body>
</html>
